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مقدمة : 
يهده الله فلا مضل له » ومن يضلل فلا هادي له » وأشهد ألا اله إلا الله وحده لا شريك واشهد أن 


ان بعضا من المبرمجين وخصوصا المبتدئين منهم لا يتبع أي معايير قياسية أثناء كتابته 
للشيفرة المصدرية أو ما يعرف بالكود البرمجي (علهء ٠٥‏ uه؟).‏ ولقد تم إعداد هذا الكتيب لتسليط 


الضوء على أهمية المعايير القياسية للشيفرة المصدرية (ئل2۲ك٣هt؟‏ ع”ا١ه))‏ والتعرف على أهم 


فکما نعلم جميعا أنه بإمكان أي شخص كتابة الشيفرة المصدرية (ملهء ع٤‏ uه؟)‏ . ومع 
قليل من الخبرة بالإمكان عمل العديد من البرامج . ولكن لعمل ذلك بالشكل الصحيح نحتاج إلى 
الكثير من التدريب والعمل. 


أن مغار ك القرة اندر فرت افر تى بكب اقاعها عد كا هه افر ة 
فبدلا من أن يكتب كل مطور الشيفرة بأسلوبه الخاص يتم توحيد طرق قياسية لكتابتها وفق معايير 
معينة. والهدف من هذه المعايير هو جعل الشيفرة المصدرية أكثر قابلية للقراءة. 


ه3 ۵ المعايير مهمة جدا خاصة للمشاريع التي يتم تطويرها من قبل العديد من المطورين. 
فهي تساعد على كتابة الشيفرة المصدرية بجودة عالية وأخطاء اقل . كما أنها تسهل من عملية 
صیانتها. 


إن النقطة الأساسية من معايير كتابة الشيفرة المصدرية ليس للقول بان طريقة معينة أفضل 


من الأخرى ولكن لتنظيم الشيفرة بطريقة تريحك كثيراً بالعمل وكذلك من يعمل بعدك على نفس 
الشيفرة. 
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هناف کر ین غر فا ك اة موف ترف ن ها اكت إن هاداد 
على معايير مكتبة ۴۴۸۴ لطريقة كتابة الشيفرة المصدرية لكونها الأكثر شعبية. حيث أن هذه 
المعايير معروفة ومقبولة أكثر من غيرها. وتعتبر الأساس للعديد من المشاريع مفتوحة المصدر مثل 
Zend Framework - Solar — Horde - Drupal‏ . ومعتمدة من قبل الكثير من المطورين. 


ويجب التنويه إلى أن هذه المعايير قابلة للتغير . كما أننا غير ملزمين تماماً بإتباعها. وعدم 
الالتزام بها وتطبيقها أثناء كتابة الشيفرة لا يؤثر على طريقة تنفيذ البرامج . 


ويبقى العديد من الجوانب التي تخص هذه المعايير بحاجة إلى المزيد من التوسع حيث أنني هنا 
حاولت تغطية أهما فيما يخص كتابة الشيفرة المصدرية بشكل عام . وليعذرني القارئ الكريم إذا وجد 
بعض الركاكة والنقص هنا أو هناك حيث أن المبتغى هو رضوان الله تعالى أولا وتسليط الضوء 
على أهمية المعايير القياسية للشيفرة المصدرية ومعرفة أهم معايير مكتبة P٤۸۴‏ لكتابتها ثانيا. 


كما يسعدني ويشرفني استقبال جميع الملاحظات والاستفسارات حول هذا الإصدار على البريد 


. majed@modernsys.net الإلكتروني‎ 


" والله ولي التوفيق " 


ماجد سليمان المليحاني 
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لمن هذا الكتيب ؟ 

هذا الكتيب يتناول أهم معايير مكتبة P۴۸۴‏ لكتابة الشيفرة المصدرية لذلك هو موجه بالدرجة 
الأولي لجميع مبرمجين لغة مم . نحن هنا لن نتطرق لمكتبة ۴۴۸۴ بشكل مفصل وإنما نتعرف 
فقط على أهم معاييرها في كتابة الشيفرة . ولمن يرغب بالاطلاع على المزيد حول مكثبة ۴۴۸۴ 
يمكن زيارة موقعها الرسمي على الرابط lلتlنلي http://pear.php.net‏ 


ما هي مکتبة ۴٤۸۴‏ ؟ 


إj‏ کٹnة PEAR‏ هي lختصlر‏ alبlرةö PHP Extension and Application Repository‏ 
مخزن ملاحق وتطبيقات مم . وبعبارة أخرى » نظام توزيع وإطار عمل لمكونات مم التي يمكن 
إعادة استخدامها. حيث تحتوي على مكونات تم برمجتها مسبقا › والتي يمكن استخدامها لجعل كتابة 
الشيفرة أكثر سهولة في م طم . توفر هذه المكتبة وحدات نمطية (sماuںdمص)‏ مفتوحة المصدر تقوم 

بتوزيعه وصيانتها . كما توفر معايير قياسية لكتابة شيفرة هذه الوحدات النمطية. 


حقوق الطبع : 

جميع حقوق الطبع محفوظة للمؤلف ( ماجد سليمان المليحاني ) . لقد تم نشر هذا الكتيب 
بشكل مجاني بصورته الرقمية فقط . ويحق لمن يريد إعادة نشره مجان بنفس الصورة الرقمية ذلك 
دون إذن مسبق من المؤلف . ويجوز عند الطلب استخدام هذا الكتيب مجانا لغير الأغراض التجارية. 
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محتويات الكتيب : 
بإذن الله تعالي سوف نتطرق إلى أهم معايير مكتبة هعم في كتابة الشيفرة المصدرية المتمثلة فيما 
يلي : 


Indenting and Line Length - رط¦سلl الإزاحة وطول‎ ٠ 
Control Structures - |ت>5م‎ io e 

Function Calls - JIgدll‎ sءاeدتwl‎ e 

Function Definitions - JIgدll تعريف‎ 

ه تعريف الفئات (الأصنlف(‏ - Class Definitions‏ 

A٣٣ھyئ‎ - المصفوفات‎ ٠ 

Comments - تٽlڙlعeتll‎ 6 

تضمين الكود من ملف خارجي - Including Code‏ 

وسم بي اتش بي - PHP Code Tags‏ 

Naming Conventions - ةڍnıتll‎ 6 


كما سوف نقوم ببعض الممارسات والتدريبات على كتابة شيفرة قياسية مثالية . ويجب التنبيه على أن 
اقفر ات المذکرر ةف هذا الكتب فما هى اتر ضيح فقط ولس لها آي انتكداء برجي فلا تر هق 
تشك قي رة في الفرة حرفا ر انما ركز على فكرة انشفر ٤‏ شكل عاد 
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Indenting and Line Length - رط¦سdl الإزاحة وطول‎ .١ 


يقصد بالإزاحة الفراغ في بداية السطر البرمجي › ويقصد بطول السطر عدد الأحرف 
لكل سطر برمجي بما فيها الفراغات التي بين الحروف. أما المعايير التي يجب إتباعها فيما 
يحض الإزاحة وطول السظر هی گتالي : 


- يجب أن تكون الإزاحة بمقدار أربع أحرف (فراغات) بدون استخدام الزر مة . 
- يجب أن يكون طول السطر البرمجي بين ۸٥-۷١‏ حرف. 

مثال لاختصار طول السطر : 

طول هذه السطر البرمجي أكثر من ٠٠١‏ حرف 


list ($name, Ş$age, SŞ$gender, $identity) = array (get_values ($name), get_values ($age), 
get_values ($gender), get_values($identity + ( ( 


یمکن اختصاره بالشکل التالي 


1ist ($name, $age, $gender, $identity) = array ( 
get_values ($name), 
get_values ($age), 
get_values ($gender), 


get_values($identity) 


حيث قمنا بوضع عناصر المصفوفة على عدة اسطر مع إزاحتها إلى الداخل بمقدار أربع أحرف 
وقوس نهاية المصفوفة في سطر مستقل بدون إزاحة. وهذا يجعل من الشيفرة أكثر قابلية للقراءة . 
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ıi 1‏ تكم - Control Structures‏ 
وتشمل کل من c۸ااسء‏ ,اناس f۲,‏ ,۴| وغیرها من بنی التحكم. 


وهذا مثال لعبارة ۴¡ لأنها الأكثر تعقيدا بينهم : 


E (Cond iEeEiteonl) lll Ceondneton#2 JN 
AEE TOR 

j1 elSelE ((CONAIELORNS) € (CONAIELON2A J) f 
IE E ZF 

} else { 
default act ion; 


} 


- يجب أن يكون هناك فراغ واحد (بمقدار حرف واحد فقط) يفصل بين عبارة التحكم وقوس 
بداية جملة التحكم وذلك للتفريق بنها وبين استدعاء الدوال وكذلك فراغ واحد بين علامات 


if ((Ş$age == 18) && ($gender == 'MALE')) { 
//... code goes here 
} 


- يفضل دائما استخدام الأقواس المتعرجة  }‏ حتى في الحالات التي يمكن الاستغناء عنها أو 
التي يكون استخدامها اختياري . فاستخدامها يزيد من قابلة قراءة الشيفرة ويقلل من حدوث 
الأخطاء المنطقية عند إضافة سطر لجملة التحكم. 


- تكتب عبارة التحكم في سطر لوحدها وينتهي السطر بعد قوس بداية التعليمة . مثال : 
ا 217 1 ) )2 iE (leo ienl) | (Cont‏ 


ل و ی کے کرت وریہ کا رون ا 
اأ“ اي ي ا نا 1 مثال 
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W3arabia | www.w3a.me E ہے‎ 


8 ee دلبو ثرى العرسة‎ e 
بار المعايير القياسية لكتابة الشفرة المصدرية‎ gn K١ 


E OCONEE ll KEC ELOMANN 


اا ا ا ا ا 1 


- یجب أن تستخدم العلامات && و || بدلا من کلماتھا AND‏ و 0R‏ 


مثال علی طع† sw‏ : 


SIE CIN KCC E LOY ل‎ 
case l1l: 

aE E ORL, 

break; 


Case 2: 
E E ORAZ, 
break; 


default: 


deEEAU E aC TOR; 
break; 
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Function Calls - JI لدو‎ ءاعدiwl‎ .۳ 


- يجب استدعاء الدالة بدون فراغ بين أسم الدالة وقوس البداية. مثال : 


get_values () 


- عند كتابة معطيات ( باراميترات ) الدالة يجب الفصل بينها بفراغ واحد فقط ويجب أن يكون 
هذا الفراغ بعد الفاصلة وليس قبلها. مثال : 


($name, Ş$age, $gender) 


- لا يجب أن يكون هناك فراغ بين أول معطى وبين قوس بداية الدالة وكذلك بين آخر معطى 
وقوس نهاية الدالة. مثال لدالة مثالية : 


get_values ($name, Ş$age, S$gender); 


- يجب أن تعيد الدالة قيمة باستخدام التعليمة ٠إ u‏ هم . 


لزيادة قابلية قراءة الكود . مثال : 


SS ROE E 
$long_variable 


EOO KSOAE 
FOO (SBA 2) 
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- ويمكن كسر قاعدة إزاحة علامة المساواة إذا كان أحد المتغيرات طويل جدا. مثال : 


SSHOEE — FOO(SOAE 
ŞthisVariableNameIsVeeeeeeeeeeryLong = foo0($baz); 


- ولزيادة قابلية قراءة الشيفرة عند استدعاء الدوال يمكن عمل إزاحة لمعطيات الدالة كما في 


: المثال التالى‎ 
SERIS seal l SOMERUNGCE1 ON PaEaAML LL, "See OMI, true); 
SERS >CEaAl ISOMER UNECE SRN PAEaAMeE er2, EMI EOL, false); 
SERS z>ECaAl lS OMEEURCETOR O, TVEEEETEEVI ONG, EEUU), 


- من المستحيل أحيانا أن يكون طول السطر البرمجى للدالة بين ۸١ - ۷١‏ حرف وخصوصا 
في حالة وجود معطيات كثيرة للدالة لذلك يمكن وضع المعطيات في أكثر من سطر كما يلي : 
Şthis->someObject->subObject->callThisFunctionWithALongName (‏ 

Ş$parameterOne, $parameterTwo, 


ŞaVeryLongParameterThree 
J); 


- علامة المساواة ( = ) : يمكن تقسيم علامة المساواة على عدة اسطر إذا تجاوزت 
المعاملات الحد المسموح به لطول السطر البرمجي ويجب أن تكون علامة المساواة في 
السطر التالي مع إزاحة بمقدار أربع فراغات. مثال : 


$GLOBALS['TSFE']->additionalHeaderData[Ş$this->strApplicationName ] 
<> SENS KA JAX Tel IAVAICE I OECOLID exEMOM::STEeEEeLEACRAK  NE xajax J); 
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Function Definitions - JIyدلl ئ تعريف‎ 


- يجب أن يكون قوس بداية الدالة وقوس نهاية الدالة في سطر لوحده ويجب إزاحة الشيفرة 
بداخل أقواس الدالة بمقدار أربع فراغات. مثال : 


EURNEE TOM FOOSE UNECE TON) 


{ 
//... code goes here 


} 


- يجب أن تعيد الدالة قيمة باستخدام التعليمة ٣٢‏ uخم؟‏ . 


- المعطيات (الباراميترات) التي تكون لها قيم افتراضية تكون في آخر قائمة المعطيات. مثال : 


GaroOl, Sarg =< "') 


- متال لدالة قياسية : 


EURNEE1 OR EOOLURSELOR( SAE, SAE = I) 
{ 
iE MOOMO E EON 
statement ; 
} 


E ê EUEN Sal, 


- مثال لدالة قياسية أخرى : 


ÊuUncCt1iOn connect (€SdSnN, Spersistentl = false) 
{ 
EE (iS EEE (CAS f 
SIASRIRME O = GCOS; 
} else { 
SdAsnNINEO = DB: Par SEDSN (SAS) F 
٣ 
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TE (SdSnanEoe ll TSdSninEol IBABEYSe L1) 


return $this->raiseError (); 


} 


EE EME EE Ue, 


يمكن وضع المعطيات في أكثر من سطر. حيث يمكن وضع بعض المعطيات في نفس السطر 
مع اسم الدالة إذا كان هناك مساحة كافية والباقي في الأسطر التالية مع عمل إزاحة بمقدار 
أربع فراغات. كما يجب وضع قوس نهاية معطيات الدالة وقوس بداية الدالة في سطر جديد 
مثال : 


function someFunctionWithAVeryLongName ($firstParameter = 'something', $secondParameter = 'booooo'", 
$third = null, $fourthParaméeter = false, $fifthParameter = 123.12, 
Ş$sixthParam = true 


f 


7//... code goes herê 
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تعريف الفئات )|لأفصنlف(‏ - Class Definitions‏ 
- يجب أن يكون قوس بداية الصنف وقوس نهاية الصنف في سطر لوحده ويجب إزاحة الشيفرة 
بداخل أقواس الصنف بمقدار أربع فراغات. مثال : 


ClASS EOO Ba 
{ 


//... code goes here 


Arrays — المصفوفات‎ .٦ 
عند تعريف مصفوفة على عدة اسطر يتم إضافة الفاصلة حتى بعد القيمة الأخيرة وهذا يعتبر‎ - 
: جملة صحيحة في لغة بي اتش بي (×ه†رء ۴۳۲ لااج) . مثال‎ 


Ssome_ array = array ( 
o > MISE, 
"spam! => ham, 


J; 


۷ llتعlيقlٽ‏ — Comments‏ 
- يجب استخدام الشرطة المائلة مع النجمة لكتابة تعليق يحتوي على أكثر من سطر. مثال : 


/x** 
* More than one lines 


سای توي على اأكثر من سره 
1 


0 
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- يجب استخدام الشرطة المائلة المكررة لكتابة تعليق من سطر واحد وعدم استخدام الرمز# . 
مثال : 


// single Line 


کا ن ا ا 


۸. تضمين الكود من ملف خارجي — Including Code‏ 


- عند تضمين كود من ملف خارجي بشروط معينة استخدم التعليمة مc٬ہ_عهںاعہ!‏ . متال : 


Sdb type = Gel dB EYBE); 

if (Ş$db_type == 'mysql') { 
LRETUGEe ONE (MVS LBER 

} 


- عند تضمين كود من ملف خارجي بدون أي شروط استخدم التعليمة ع" ۲٩u re_0‏ . 
مثال: 


Te QULE OnNEe( Meader BAB), 


PHP Code Tags — وسم بي اتش بي‎ .٩ 
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Naming Conventions — Anî .1 ١ 


يجب التتبيه إلى أنه تختلف تسمية المتغيرات والدوال التي تكون خار ج الأصناف (ءعءءهاء) 
قليلا عن التسمية داخلها. 


- يتم تسمية المتغيرات بأحرف صغيره ويفصل بين الكلمات في اسم المتغير بشرطة سفلية. 
Sdb type = mysql;‏ 
- يتم تسمية الثوابت بأحرف كبيرة ويفصل بين الكلمات في اسم الثابت بشرطة سفلية. 


dere Ine ( SITE PATH, SSICEPAED); 


- يتم تسمية الدوال بأحرف صغيرة ويفصل بين الكلمات في اسم الدالة بشرطة سفلية. 
get_db_type();‏ 
يتم تسمية الأصناف (ءعءءهاء) بحرف كبير في بداية كل كلمة من أسم الصنف ويفصل بين 


الكلمات في بشرطة سفلية. كما يجب أن يكون للاسم دلالة وصفية . وتجنب اختصار الاسم 
قذر الامكان , مشال : 


HIME UBLIOSAId BF EOE 
HTML_ Template 


- يتم تسمية الدوال والمتغيرات داخل الصنف بحرف كبير في بداية كل كلمة من أسم ماعدا 
1 لكلمة الأولي مثال : 


Ea 
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// اساء م ترات‎ 
SEOUR EOE 
ŞclearCache 


أاء وال // 

Je EDaAEaA N) 
CORRES E () 
buildSomeWidget () 


- يجب وضع شرطة سفلية قبل اسم الدوال الخاصة (عخه۷آ۴۲) في داخل الصنف. مثال : 


SOE (0) 
_initTree() 
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بعض الممارسات على كتابة شيفرة قياسية : 
لو نظرنا إلى الكود التالي : 


Ş$name='Majed'; 

SEOURNEEV= SAaUAT AEaDTA LL, 
Scity= Madinah; 
$site='www.yamamah.org'"; 
ŞSemail='mE amr iGhotmai l . com! 


Sdala= My mame lS enamel GAS lT aM LEON COUNTY SECO 
SEOnNEACE= I YOU ean CONESCE Me ERNEOMGN My Slee l1 SSIEE 1 OE My email l€ Sema; 
E (Same Ma Jed) eCeRNO SdaEa OE 4 I OCOMEACE,} 


يمكن كتابته بصورة أفضل ليصبح أكثر قابلية للقراءة كما يلي : 


Sname = 'Majed'; 

SEOUNEEY = SAUd1 AFAD; 

SEE = "Madinah; 

$site = 'www.yamamah.org'; 

Şemail = 'mr_amri@Ghotmail.com'" 

$data > My name i1S 1l Shame. aNd TÛ aM EEOM ll. SEOUNEEY 1 SOE? 
SESNEAGE > YoU Gan COnNEaCE Me ENEOUON my Site 1l SS1CE | OF My eMail 1 Semail; 
TE (Sname == Majed) 


CERG GISELE 7 OCONEE, 


حيث قمنا بإزاحة علامة المساواة بين المتغيرات وذلك لوجود متغيرات ذو اسم قصير وأخرى ذو 
اسم طويل. وكذلك أضفنا فراغ واحد (بمقدار حرف واحد فقط) يفصل بين عبارة التحكم وقوس بداية 
جملة ۴¡ . وأيضا تم إزاحة الشيفرة داخل أقواس التعليمة ۴¡ ( الأقواس المتعرجة [) ) بمقدار أربع 


اخوف: 
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ولو نظرنا إلى المثال التالي: 


E CEOS 


SOE = 
1E (SPM) [{ 
Sham => U. 


E (OADEY) | 
SEAM = Uz 


يكون أسهل في القراءة إذا أضفنا سطر فارغ بين كل جملة من جمل f‏ كما يلي : 


E (EON 


SDA — 
1 
iE ESEN | 
SE — ME 


E (OBADEY) 
SEAM > U; 


1 
لو أردنا تقسيم عبارة ¡f‏ التالية على عدة اسطر 
TE SeondTEIoOnI || SFEonAIEIONZ &&6 CONATEIONS ES SEONALETONA)‏ 


11 CS OS 


يمكن إعادة كتابتها بالشكل التالي : 


iE SESAME EOL 
lÎ SECON LOMA 
E SEO ME LOM 
&& $condition4 


//... code goes here 


1 
W3arabia | www.w3a.me 1 ) 


0 دبلیو ثري العربية E‏ 2 
wdarabia K4‏ ` المعايير القياسية لكتابة الشفرة المصدرية 


وأفضل الحالات بالطبع هو عندما لا يكون هناك حاجة إلى تقسيم السطر البرمجي لعدة اسطر. 

عندما تكون الجملة الشرطية طويلة بما يكفي ويجب تقسيمها إلى عدة اسطر يكون من 
الأفضل تبسيطها. وفي متل هذه الحالات يمكنك التعبير عن الشروط كمتغيرات ومقارنة هذه 
المتغيرات في العبارة الشرطية ¡f‏ بهذه الطريقة يمكن تقسيم الشرط إلى مجموعات اصغر. ولتوضيح 
ذلك بشكل اكبر يمكن إعادة كتابة الشيفرة السابقة بالشكل التالي : 


E FOO = COMICON lll EOC CLO ZN F 
SL Dar = (CONICET GE SEOMAENOMA 


r 


2 


HE OLS EOS GCE CIS BAF) | 
//... code goes here 
} 


کما یمکن استخدام نفس هذه القاعدة مع معامل الشرط الثلاڻي ) Ternary operators‏ ( إِذا يمكن 
التقسيم إلى عدة اسطر مع الحفاظ على علامة الاستفهام والنقطتين في بداية السطر . مثال ` 


علامة الاستقهام و النقطتن ق تفس السطر ⁄/ 
Sa — SEONIIEIONL &S SCORIIEIONZ‏ 
SEO 7. SBaAE;‏ %3 


علامة الاستفهام في سطر و النقطتين في سطر مستقل // 

SD = SEONIIEIOMS && SCONCE ORNA 
SS SEO MARN CNIS IS EOS ORG WOhAE SHOU OO 
; SGar; 
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للحفاظ على قابلية القراءة للدوال ومعطياتها من الحكمة إعادة قيمة مبكرا عند تطبيق شرط بسيط في 


بداية الدالة . لو نظرنا إلى المثال التالي : 


Saz) 


EUnNGE ION EOO(SOAR, 
{ 


E Nl CE ES 


lculated_value; 


من الأفضل إعادة القيمة |ام مبكرا إذا لم يتحقق الشرط كما يلي : 


Saz) 


E O FOO) 
ا‎ 
7 
4 
4 
1 
4 
ا‎ 
1 
0 LEE 
اال اة ر‎ 
FeElUED SCal 
} else { 


E EUE RM MULL 


} 


EUnCGE1ON FEFOO(SBaAF, 
{ 


عه عدم كق الهرط 7 


TE (USFS) 1 


FEEUEDN MULL; 


} 


3 ا 4 


E GC FOO 
// يفترض‎ 
7 ان‎ 
44 کین‎ 
4 E 
// شيفرة‎ 
1 خا‎ 
و‎ 
4 
0 EEE 
اة هة ر‎ 


return Ş$calculated_value; 
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الخاتمة 
في الختام احمد الله سبحانه وتعالي حمدا كثيرآً طيبا مباركا كما يليق بجلال وجهه وعظيیم 
سلطانه » أن وفقني لكتابة هذه الأسطر عن هذا الموضوع » فان أصبت فمن الله وحده » وان أخطأت 
فمن نفسي ومن الشيطان . وأتمنى أن أكون قدمت ما هو مفيد حول المعايير القياسية لكتابة الشيفرة 
المصدرية . وفي حال وجود ملاحظات أو أخطاء في هذا الإصدار يسعدني استقبالها على البريد 


. majed@modernsys.net الإلكتروني‎ 


كما أتقدم بجزيل الشكر والعرفان لمؤسسة دبليو ثري العربية الغير ربحية لما تقدمه من تعليم 
مجاني للغات برمجة وتصميم تطبيقات الويب للمستخدم العربي › وما تنشره من مواضيع ودروس 
قيمة لإثراء المحتوى العربي. 


أجمعين 
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المراجع 


e Pear Coding Standards. 
e zend framework wiki - PHP Coding Standard (draft). 
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